NAME
	GU_CreateGadgetA -- Create a gadget with built-in hotkey support.

   SYNOPSIS
	gad = CreateGadgetA(kind, prevgad, newgad, taglist)
	D0,A0               D0    A0       A1      A2

	struct Gadget *GU_CreateGadgetA(ULONG, struct Gadget *,
					struct NewGadget *, struct TagItem *);

   FUNCTION
	GU_CreateGadgetA() allocates and initializes a new gadget of the
	specified kind, and attaches it to the previous gadget. The gadget
	is created based on the supplied kind, NewGadget structure, and
	tags.

	This function differs from the GadTools equivalent by supporting
	some extra tags to allow the gadget to be selected using the
	keyboard.

   INPUTS
	kind - kind of gadget to create. One of the XXX_KIND values
	       defined in <libraries/gadtools.h>.

	prevgad - pointer to the previous gadget that this new gadget
		  should be attached to. This function will fail if
		  this value is NULL.

	newgad - a filled in NewGadget structure describing the desired
		 gadget's size, position, label, etc.

	taglist - pointer to an array of tags providing optional extra
		  parameters, or NULL.

   TAGS
	All kinds:

	GT_Underscore - Indicates the symbol that precedes the character
		in the gadget label to be underscored. This can be to
		indicate keyboard equivalents for gadgets. GadUtil has
		the ability to process the keyboard equivalents if some
		other tags are used.

	GU_Hotkey - This tag selects the hotkey to be used as an automatic
		keyboard command for the gadget. The ti_Data field should
		contain the ASCII or RAWKEY code for the hotkey.
		This tag may be used together with the GU_HotkeyCase and
		GU_LabelHotkey. The GU_RawKey tag requires this tag.

	GU_HotkeyCase - This tag makes the keyboard command case-sensitive.
		This tag may not be used with GU_RawKey.

	GU_LabelHotkey - This tag picks the hotkey from the gadget text
		field in the NewGadget structure when the gadget is created.
		If no key is marked with the underscore, the GU_HotKey code
		will be used.

		This tag supports and requires the GT_Underscore tag. The
		character that was given in the GT_Underscore tag will be
		used to find the code for the hotkey.

	GU_RawKey - This tag makes the hotkey code to a RAWKEY code. All
		keys on the keyboard has one rawkey code that matches the
		key.

		If your program also gets VANILLAKEY events, you must be
		careful when selecting the rawkey code to be used as a
		keyboard shortcut for this gadget. RAWKEY events will only
		be sent for special keys (such as the HELP, Control, Alt
		and function keys) that don't map to a single character. 
		All keys that maps to a single character will be processed
		as a VANILLAKEY event.

		This tag may not be used with (and will also disable) the
		GU_HotkeyCase and GU_LabelHotkey tags.

	Kind specific tags:
		See the GadTools function CreateGadgetA for all other tags.

   RESULT
	gad - pointer to the new gadget, or NULL if the allocation failed
	      or if prevgad was NULL.

   NOTES
	Note that the ng_VisualInfo and ng_TextAttr fields of the NewGadget
	structure must be set to valid VisualInfo and TextAttr pointers, or
	this function will fail.

   SEE ALSO
	GU_FreeGadgets(), GU_SetGadgetAttrsA(), GU_GetVisualInfoA(),
	GU_GetIMsg(), gadtools/CreateGadgetA, <libraries/gadtools.h>

Converted on 19 Jul 1996 with RexxDoesAmigaGuide2HTML by Michael Ranner.